package com.ruoyi.system.service;

import java.util.List;
import com.ruoyi.system.domain.SuperPoint;
import com.ruoyi.system.domain.vo.SuperPointVo;

/**
 * 用户积分Service接口
 * 提供用户积分管理的核心业务方法
 * 
 * @author ruoyi
 * @date 2025-08-13
 */
public interface ISuperPointService 
{
    /**
     * 查询用户积分
     * 
     * @param id 用户积分主键
     * @return 用户积分
     */
    public SuperPoint selectSuperPointById(Long id);

    /**
     * 根据用户ID查询积分信息
     * 业务说明：用于快速查询指定用户的积分信息，常用于用户登录后显示积分
     * 应用场景：用户个人中心、积分查询页面、积分余额显示等
     * 
     * @param userId 用户ID
     * @return 用户积分记录，如果用户没有积分记录则返回null
     */
    public SuperPoint selectSuperPointByUserId(Long userId);

    /**
     * 查询用户积分列表
     * 
     * @param superPoint 用户积分查询条件
     * @return 用户积分集合
     */
    public List<SuperPoint> selectSuperPointList(SuperPoint superPoint);

    /**
     * 查询用户积分列表（包含用户信息）
     * 业务说明：通过关联查询获取积分信息和用户基本信息，用于管理后台显示
     * 包含的信息：用户昵称、用户账号、积分数量、创建时间、更新时间等
     * 应用场景：管理后台积分管理页面、积分统计报表等
     * 
     * @param superPoint 用户积分查询条件
     * @return 包含用户信息的积分VO集合
     */
    public List<SuperPointVo> selectSuperPointVoList(SuperPoint superPoint);

    /**
     * 新增用户积分
     * 
     * @param superPoint 用户积分
     * @return 结果
     */
    public int insertSuperPoint(SuperPoint superPoint);

    /**
     * 修改用户积分
     * 
     * @param superPoint 用户积分
     * @return 结果
     */
    public int updateSuperPoint(SuperPoint superPoint);

    /**
     * 增加用户积分
     * 业务说明：用于用户获得积分时的业务场景，如购物、签到、活动奖励等
     * 实现逻辑：直接在现有积分基础上增加指定数量，无上限限制
     * 安全考虑：建议在调用前验证积分的合法性，防止恶意增加积分
     * 
     * @param userId 用户ID
     * @param points 增加的积分数（必须为正数）
     * @return 影响的行数，1表示成功，0表示用户不存在积分记录
     */
    public int increaseUserPoints(Long userId, Integer points);

    /**
     * 减少用户积分
     * 业务说明：用于用户消费积分时的业务场景，如积分兑换、积分抵扣等
     * 实现逻辑：确保积分不会变为负数，如果积分不足则操作失败
     * 安全考虑：在SQL层面进行积分检查，防止积分变为负数
     * 
     * @param userId 用户ID
     * @param points 减少的积分数（必须为正数）
     * @return 影响的行数，1表示成功，0表示积分不足或用户不存在
     */
    public int decreaseUserPoints(Long userId, Integer points);

    /**
     * 批量删除用户积分
     * 
     * @param ids 需要删除的用户积分主键集合
     * @return 结果
     */
    public int deleteSuperPointByIds(Long[] ids);

    /**
     * 删除用户积分信息
     * 
     * @param id 用户积分主键
     * @return 结果
     */
    public int deleteSuperPointById(Long id);
}
